home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / dejagnu.lha / dejagnu-1.0.1 / tcl / doc / AssembCmd.3 < prev    next >
Text File  |  1993-02-14  |  3KB  |  86 lines
  1. '\"
  2. '\" Copyright 1989-1992 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_AssembleCmd tcl
  12. .BS
  13. .SH NAME
  14. Tcl_CreateCmdBuf, Tcl_AssembleCmd, Tcl_DeleteCmdBuf \- buffer pieces of Tcl commands
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. Tcl_CmdBuf
  20. \fBTcl_CreateCmdBuf\fR()
  21. .sp
  22. \fBTcl_DeleteCmdBuf\fR(\fIbuffer\fR)
  23. .sp
  24. char *
  25. .VS
  26. \fBTcl_AssembleCmd\fR(\fIbuffer\fR, \fIstring\fR)
  27. .VE
  28. .sp
  29. int
  30. \fBTcl_CommandComplete\fR(\fIcmd\fR)
  31. .SH ARGUMENTS
  32. .AS Tcl_CmdBuf *string;
  33. .AP Tcl_CmdBuf buffer in
  34. Token for a command buffer (the result of some previous call to
  35. \fBTcl_CreateCmdBuf\fR).
  36. .AP char *string in
  37. Additional piece of command input to be added to anything currently
  38. buffered.
  39. .AP char *cmd in
  40. .VS
  41. Command string to test for completeness.
  42. .VE
  43. .BE
  44.  
  45. .SH DESCRIPTION
  46. .PP
  47. These procedures provide a convenient mechanism for assembling
  48. Tcl commands from an input source where command boundaries are not
  49. obvious.  For example, if input is being read from a terminal, a user
  50. may type commands that span multiple lines.  In situations like
  51. this, \fBTcl_AssembleCmd\fR can be called with the individual lines
  52. as they are received.  It buffers the lines internally and returns
  53. full commands when they are complete.
  54. .PP
  55. A command buffer is created by calling \fBTcl_CreateCmdBuf\fR, and
  56. it is deleted by calling \fBTcl_DeleteCmdBuf\fR.  There may be any
  57. number of command buffers for a particular program or even for a
  58. particular interpreter;  in most cases there should be one
  59. buffer for each independent source of command input.
  60. .PP
  61. When input arrives from a source you should call \fBTcl_AssembleCmd\fR,
  62. passing it the new input as the \fIstring\fR argument.
  63. \fBTcl_AssembleCmd\fR will add the new input to anything currently
  64. buffered in \fIbuffer\fR.  If the information now buffered represents
  65. a complete Tcl command (i.e. there are no unclosed quotes, braces,
  66. brackets, or variable references),
  67. then \fBTcl_AssembleCmd\fR returns a pointer to the complete command
  68. and arranges for the buffer to be cleared on the next call to
  69. \fBTcl_AssembleCmd\fR.  If the command is still incomplete (because,
  70. for example, there are unmatched braces) then \fBTcl_AssembleCmd\fR
  71. returns NULL.  \fBTcl_AssembleCmd\fR keeps a private copy of the
  72. command being assembled, so that the caller need not preserve the
  73. contents of \fIstring\fR between calls to \fBTcl_AssembleCmd\fR.
  74. \fBTcl_AssembleCmd\fR supports commands of arbitrary length (up to
  75. the total memory limit imposed by the operating system, if any).
  76. .PP
  77. .VS
  78. The procedure \fBTcl_CommandComplete\fR takes a Tcl command string
  79. as argument and determines whether the command string is complete
  80. in the sense defined above.
  81. If so then it returns 1; otherwise it returns 0.
  82. .VE
  83.  
  84. .SH KEYWORDS
  85. assemble, buffer, partial command
  86.